package com.kexilo.exception.service;

import com.kexilo.exception.domain.ExceptionRecord;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * 异常处理服务接口
 * 定义了异常处理的抽象接口，不依赖任何具体实现
 * 
 * @author Kexilo
 */
public interface ExceptionService {
    
    /**
     * 记录异常信息
     * 
     * @param exceptionRecord 异常记录
     * @return 操作结果
     */
    boolean recordException(ExceptionRecord exceptionRecord);
    
    /**
     * 异步记录异常信息
     * 
     * @param exceptionRecord 异常记录
     * @return 异步操作结果
     */
    CompletableFuture<Boolean> recordExceptionAsync(ExceptionRecord exceptionRecord);
    
    /**
     * 批量记录异常信息
     * 
     * @param exceptionRecords 异常记录列表
     * @return 成功记录的数量
     */
    int batchRecordExceptions(List<ExceptionRecord> exceptionRecords);
    
    /**
     * 根据异常ID查询异常记录
     * 
     * @param exceptionId 异常ID
     * @return 异常记录
     */
    ExceptionRecord getExceptionById(String exceptionId);
    
    /**
     * 根据链路追踪ID查询异常记录
     * 
     * @param traceId 链路追踪ID
     * @return 异常记录列表
     */
    List<ExceptionRecord> getExceptionsByTraceId(String traceId);
    
    /**
     * 根据异常类型查询异常记录
     * 
     * @param exceptionType 异常类型
     * @param limit 限制数量
     * @return 异常记录列表
     */
    List<ExceptionRecord> getExceptionsByType(String exceptionType, int limit);
    
    /**
     * 查询未处理的异常记录
     * 
     * @param limit 限制数量
     * @return 异常记录列表
     */
    List<ExceptionRecord> getUnresolvedExceptions(int limit);
    
    /**
     * 查询高优先级异常记录
     * 
     * @param limit 限制数量
     * @return 异常记录列表
     */
    List<ExceptionRecord> getHighPriorityExceptions(int limit);
    
    /**
     * 更新异常状态
     * 
     * @param exceptionId 异常ID
     * @param status 新状态
     * @param remark 备注
     * @return 操作结果
     */
    boolean updateExceptionStatus(String exceptionId, String status, String remark);
    
    /**
     * 删除异常记录
     * 
     * @param exceptionId 异常ID
     * @return 操作结果
     */
    boolean deleteException(String exceptionId);
    
    /**
     * 清理过期异常记录
     * 
     * @param daysBeforeNow 多少天之前
     * @return 清理的数量
     */
    int cleanupExpiredExceptions(int daysBeforeNow);
    
    /**
     * 发送异常通知
     * 
     * @param exceptionRecord 异常记录
     * @return 发送结果
     */
    boolean sendNotification(ExceptionRecord exceptionRecord);
    
    /**
     * 发送邮件通知
     * 
     * @param exceptionRecord 异常记录
     * @param recipients 收件人列表
     * @return 发送结果
     */
    boolean sendEmailNotification(ExceptionRecord exceptionRecord, List<String> recipients);
    
    /**
     * 发送短信通知
     * 
     * @param exceptionRecord 异常记录
     * @param phoneNumbers 手机号列表
     * @return 发送结果
     */
    boolean sendSmsNotification(ExceptionRecord exceptionRecord, List<String> phoneNumbers);
    
    /**
     * 发送钉钉通知
     * 
     * @param exceptionRecord 异常记录
     * @param webhookUrl 钉钉机器人WebhookURL
     * @return 发送结果
     */
    boolean sendDingTalkNotification(ExceptionRecord exceptionRecord, String webhookUrl);
    
    /**
     * 添加到死信队列
     * 
     * @param exceptionRecord 异常记录
     * @return 操作结果
     */
    boolean addToDeadLetterQueue(ExceptionRecord exceptionRecord);
    
    /**
     * 从死信队列获取异常
     * 
     * @param limit 限制数量
     * @return 异常记录列表
     */
    List<ExceptionRecord> getFromDeadLetterQueue(int limit);
    
    /**
     * 重试处理死信队列中的异常
     * 
     * @param exceptionId 异常ID
     * @return 操作结果
     */
    boolean retryDeadLetterException(String exceptionId);
    
    /**
     * 获取异常统计信息
     * 
     * @return 统计信息
     */
    Map<String, Object> getExceptionStatistics();
    
    /**
     * 获取异常趋势数据
     * 
     * @param days 天数
     * @return 趋势数据
     */
    Map<String, Object> getExceptionTrends(int days);
    
    /**
     * 获取异常排行榜
     * 
     * @param type 排行类型（type, class, module等）
     * @param limit 限制数量
     * @return 排行数据
     */
    List<Map<String, Object>> getExceptionRankings(String type, int limit);
    
    /**
     * 导出异常记录
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @param format 导出格式（EXCEL, CSV, PDF等）
     * @return 导出文件路径
     */
    String exportExceptions(String startTime, String endTime, String format);
    
    /**
     * 检查异常是否需要发送通知
     * 
     * @param exceptionRecord 异常记录
     * @return 是否需要通知
     */
    boolean shouldSendNotification(ExceptionRecord exceptionRecord);
    
    /**
     * 检查异常是否为重复异常
     * 
     * @param exceptionRecord 异常记录
     * @return 是否为重复异常
     */
    boolean isDuplicateException(ExceptionRecord exceptionRecord);
    
    /**
     * 获取异常相似度
     * 
     * @param record1 异常记录1
     * @param record2 异常记录2
     * @return 相似度（0.0-1.0）
     */
    double calculateSimilarity(ExceptionRecord record1, ExceptionRecord record2);
    
    /**
     * 根据异常记录推荐解决方案
     * 
     * @param exceptionRecord 异常记录
     * @return 解决方案建议
     */
    List<String> recommendSolutions(ExceptionRecord exceptionRecord);
    
    /**
     * 分析异常模式
     * 
     * @param period 分析周期（天）
     * @return 异常模式分析结果
     */
    Map<String, Object> analyzeExceptionPatterns(int period);
    
    /**
     * 检查服务是否可用
     * 
     * @return 是否可用
     */
    boolean isAvailable();
    
    /**
     * 获取服务健康状态
     * 
     * @return 健康状态信息
     */
    Map<String, Object> getHealthStatus();
    
    /**
     * 获取服务名称
     * 
     * @return 服务名称
     */
    default String getServiceName() {
        return this.getClass().getSimpleName();
    }
    
    /**
     * 获取服务版本
     * 
     * @return 服务版本
     */
    default String getServiceVersion() {
        return "1.0.0";
    }
    
    /**
     * 异常变更通知（可扩展用于数据同步）
     * 
     * @param exceptionId 异常ID
     * @param operation 操作类型：CREATE, UPDATE, DELETE
     * @param exceptionRecord 异常记录
     */
    default void notifyExceptionChange(String exceptionId, String operation, ExceptionRecord exceptionRecord) {
        // 默认实现为空，具体实现类可以覆盖此方法
    }
    
    /**
     * 异常处理器接口
     */
    @FunctionalInterface
    interface ExceptionHandler {
        /**
         * 处理异常
         * 
         * @param exceptionRecord 异常记录
         * @return 处理结果
         */
        boolean handle(ExceptionRecord exceptionRecord);
    }
    
    /**
     * 异常过滤器接口
     */
    @FunctionalInterface
    interface ExceptionFilter {
        /**
         * 过滤异常
         * 
         * @param exceptionRecord 异常记录
         * @return 是否通过过滤
         */
        boolean filter(ExceptionRecord exceptionRecord);
    }
    
    /**
     * 注册异常处理器
     * 
     * @param handler 异常处理器
     */
    default void registerExceptionHandler(ExceptionHandler handler) {
        // 默认空实现
    }
    
    /**
     * 注册异常过滤器
     * 
     * @param filter 异常过滤器
     */
    default void registerExceptionFilter(ExceptionFilter filter) {
        // 默认空实现
    }
}
